home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / program / 569 / rsctools / rmerge.man < prev    next >
Text File  |  1992-06-01  |  14KB  |  241 lines
  1. RMERGE                     ST Programmer's Manual                    RMERGE
  2.  
  3.  
  4. NAME
  5.  
  6.       rmerge - selectively merges GEM resource files
  7.  
  8. DESCRIPTION
  9.  
  10.       Rmerge is a utility designed to facilitate merging of GEM resource
  11.       files.  Existing resource construction programs provide this
  12.       capability only to a very limited degree; in particular, they tend
  13.       not to preserve tree and object names when copying an entity from
  14.       one file to another, making it very difficult to share resource
  15.       files or maintain a resource file "library."  In addition, most
  16.       editors are limited to editing one file at a time; although they
  17.       provide a clipboard for inter-resource file pasting, the clipboard
  18.       can hold only one tree at a time, so that copying multiple trees
  19.       involves loading, saving, and reloading and resaving of the resource
  20.       files.  Rmerge was written to address these problems and make
  21.       resource file merging as effortless as possible.
  22.  
  23.       Rmerge is a GEM program that takes no command line options.  When run,
  24.       rmerge presents the file selector; enter the name of a resource file
  25.       you wish to merge.  As long as Cancel wasn't pressed, rmerge presents
  26.       the file selector a second time; enter the second resource file to
  27.       merge, or just press Cancel to proceed with the program.  After the
  28.       "source resource file(s)" have been designated, rmerge displays its
  29.       main dialog box.
  30.  
  31.          Note: rmerge understands the four definition file formats known to
  32.          the author: DEF (DRI RCS 1), DFN (DRI RCS 2), RSD (Kuma/MWC), and
  33.          HRD (Wercs).  At least one file having the same basename as the
  34.          resource file and ending with one of these extensions must be
  35.          present in the same directory as the resource file; rmerge will
  36.          otherwise abort.  If more than one definition file is present,
  37.          rmerge will inform you and present the file selector, so that you
  38.          may choose the definition file rmerge will use.
  39.  
  40.       The main rmerge dialog contains three scrollable lists.  The two
  41.       leftmost lists contain the tree-level (i.e. dialogs, panels, menus,
  42.       free strings, alerts, and free images) item names for the source
  43.       resource files, while the rightmost list contains the tree-level
  44.       names for the merged or target resource file, and this list is
  45.       initially empty.  The "Show" radio buttons control which group of
  46.       names rmerge will display at any given time.
  47.  
  48.       Now, consider the four buttons in the lower right corner of the
  49.       rmerge dialog.  The "Copy" and "Replace" buttons act upon selected
  50.       items in the two source lists; after selecting some source items
  51.       and pressing Copy, for example, the item names appear in the target
  52.       list.  The "Remove" button removes selected items from the target
  53.       list.  The "Copy All" button requires no selected items; rather, it
  54.       duplicates either the first or second resource file in the target
  55.       file.  Copy All should only be used when the target resource is
  56.       empty; otherwise, name conflicts are very likely to occur, causing
  57.       the operation to be aborted.
  58.  
  59.       Copy and Replace differ in how they deal with name conflicts.  As
  60.       mentioned earlier, rmerge preserves names when constructing the target
  61.       resource, and duplicate names are not allowed.  When merging trees into
  62.       the target, a name conflict may occur in the tree name and also among
  63.       the objects comprising the tree and any other names currently in the
  64.       target.  Rmerge identifies both types of conflicts.  Copy aborts upon
  65.       finding any name conflicts, while Replace may or may not, depending
  66.       on the type of the conflict.  If Replace discovers the item name is
  67.       duplicated within the same item class (e.g. a dialog-menu conflict),
  68.       it will proceed to replace the target item with the source item.
  69.       If, on the other hand, Replace discovers an inter-class conflict, such
  70.       as a dialog-free image mismatch, it will report the error and abort
  71.       the operation.  When working with trees, Replace will still report an
  72.       error if it discovers a conflict between an object name within the source
  73.       item and any names currently in the target, unless the conflict is in
  74.       the item being replaced.  When the item doesn't already appear in the
  75.       target resource, Replace acts like Copy.
  76.  
  77.       Copy and Replace both copy all selected items in the first source
  78.       resource before starting on the selected items in the second.  Copy
  79.       always appends items to their respective classes.
  80.  
  81.       After constructing the target resource, click "Save" to save the new
  82.       resource file.  Rmerge presents the file selector, and after the filename
  83.       has been chosen, rmerge presents an alert box allowing a choice of
  84.       definition file formats.  After the definition file format is chosen,
  85.       rmerge saves the resource file, definition file, and C header file;
  86.       the latter two filenames are built from the target resource file
  87.       basename and the appropriate extensions.
  88.  
  89.       Note: one of the more frustrating aspects of working with resource
  90.       files is the need to recompile entire programs when the tree-level
  91.       structure of the resource file changes.  For example, if one deletes
  92.       a tree, the indexes of the trees following it in the resource file
  93.       all change by one, and the program must be recompiled.  Rmerge can't
  94.       do anything about this; however, under some circumstances one can
  95.       avoid a global recompile.  Specifically, if using rmerge to add some
  96.       trees to an existing resource, as long as the new trees are added to
  97.       the target _after_ the existing resource has been duplicated in the
  98.       target via "Copy All", only those files dependent on the new trees
  99.       need be recompiled.  Similarly, if a tree in the target is _replaced_,
  100.       only those modules dependent on that tree need be recompiled.
  101.  
  102. EXAMPLES
  103.  
  104.       Example 1
  105.  
  106.       Suppose two programmers are working on a project and sharing the
  107.       resource file; programmer 1 adds some trees to the resource, and
  108.       programmer 2 would like to update his idea of the resource to
  109.       conform to programmer 1's.  The merge process would proceed as
  110.       follows:
  111.  
  112.          Step 1: programmer 2 loads his idea of the resource as the first
  113.             source resource and programmer 1's as the second,
  114.  
  115.          Step 2: he then clicks "Copy All", selecting the "1" button in the
  116.             alert box that is presented (this copies his idea of the resource
  117.             in its entirety to the target),
  118.  
  119.          Step 3: he then identifies the new trees in programmer 1's resource,
  120.             selecting them in the scrollable list, and clicks "Copy"; two
  121.             possibilities exist:
  122.  
  123.                a. a "name conflict" alert will appear, indicating that the
  124.                   two progammers have accidentally used duplicate names,
  125.                   in which case they need to agree on a solution and correct
  126.                   the problem with the resource construction program,
  127.                b. the operation will silently succeed.
  128.  
  129.          Step 4: he saves the merged resource and quits rmerge.
  130.  
  131.          Step 5: he compiles any files dependent on the new trees; since
  132.             he used "Copy All" and _added_ trees, free strings, etc., the
  133.             tree-level structure of the resource doesn't change, as far as
  134.             his earlier code is concerned.
  135.  
  136.       Example 2
  137.  
  138.          Assume the scenario in example 1, except that programmer 1 modifies
  139.          some _existing_ trees.  Programmer 2 would follow the same steps as
  140.          given above, except that he would click "Replace" in Step 3 rather
  141.          than "Copy", because Replace allows name conflicts between a tree
  142.          and its objects and the tree and objects it's replacing.  Note,
  143.          however, that if the source tree contains other name conflicts, say
  144.          between one of its objects and a free image or an object in another
  145.          tree, Replace will correctly abort the operation, and the resource
  146.          editor is required to resolve the conflict.  Step 5 also changes;
  147.          the programmer must recompile any modules dependent on the trees
  148.          that were _replaced_; modules dependent upon unaffected trees
  149.          needn't be recompiled.
  150.  
  151.       Example 3
  152.  
  153.          A programmer has designed a resource file containing some trees
  154.          he wishes to use in a new application.  He would simply load the
  155.          existing resource into rmerge, foregoing loading the second source
  156.          resource, copy everything he wishes to reuse to the target resource,
  157.          and save the new resource.  Since he can selectively transport
  158.          items to the target resource, this is significantly easier than
  159.          using a resource editor (the equivalent process in the latter type
  160.          of program would require deleting everything he _doesn't_ want,
  161.          rather than including everything he _does_, because resource editors
  162.          don't preserve item names).
  163.  
  164.       Example 4
  165.  
  166.          A programmer has a resource built with the DRI editor, and he now
  167.          wishes to use the Kuma editor.  He can translate the definition file
  168.          from DFN to RSD by loading the file into rmerge, clicking Copy All,
  169.          and saving the new file, choosing the Kuma (RSD) definition format.
  170.  
  171. NOTES
  172.  
  173.       The Kuma/Mark Williams resource editor treats TEDINFOs differently
  174.       from the other editors known to the author.  Specifically, it pads
  175.       the `te_ptext' fields with zeros so that they are at least as long
  176.       as their corresponding `te_pvalid' fields, presumably as a safeguard
  177.       against overflowing the array when operating the form, despite the
  178.       common practice of patching the structures at run-time with larger
  179.       arrays.  Thus when saving a target resource for the Kuma definition
  180.       file format, rmerge follows this (undocumented) convention.
  181.  
  182.       Rmerge was built using a custom interface library.  All the buttons
  183.       in the dialog box have associated hotkeys, indicated by underline
  184.       or color.  To select a button from the keyboard, press Alt plus the
  185.       highlighted character, or since the dialog contains no edit fields,
  186.       just press the character itself (Alt isn't required unless edit
  187.       fields are present).  Esc/Undo select the "Cancel" action, when
  188.       appropriate.  The scrollable lists support continuous selection while
  189.       scrolling.  Shift-clicking selects an item when one or more items is
  190.       selected, adding the item to the group of selected items.  Control-Alt-
  191.       clicking a list item selects every item in the list.
  192.  
  193.       The File Selector provides a number of improvements on the GEM file
  194.       selector.  For one, you can navigate directories as you would in a
  195.       command line shell, typing things like "..\cli", "e:", and "c:\auto"
  196.       followed by pressing Return.  You can also enter wildcard specifications
  197.       in the same manner, and wildcards act much like they do under Unix
  198.       systems.  You can use character classes as in "a*[a-z][^aeiou]?";
  199.       "*" matches every file, "*.*" matches only files with extensions, and
  200.       "*." matches only files without extensions.  Unlike with TOS, wildcards
  201.       such as "*f*" are meaningful, and the dot in a filename isn't treated
  202.       specially, except that a "?" won't match it, and the "xxx." pattern
  203.       matches files without extensions.  Of course, you can always enter
  204.       a more or less fully qualified path for the filename you wish to select
  205.       in the edit field; as long as it doesn't contain wildcard characters
  206.       and isn't a directory, the File Selector will return the filename to
  207.       the caller.  Sometimes a list of extensions is provided on the right
  208.       side of the File Selector; click on any one of these to replace the
  209.       current extension.  Clicking an already-selected extension button
  210.       removes the extension from the current filemask; double-clicking an
  211.       already-selected extension button removes the extension but leaves the
  212.       dot.  Double clicking an already-selected drive button forces a media
  213.       change on that drive.  You can back up to parent directories by clicking
  214.       the ".." entry at the top of the directory list, typing "..", or by
  215.       clicking on the desired directory name in the "Path" line.  Clicking the
  216.       current directory name in "Path" copies the entire path to the edit
  217.       field, while clicking the filemask portion copies only the mask.
  218.       Although rmerge has no use for this feature, depending on how it's
  219.       called, the File Selector can return multiple files to the caller.
  220.  
  221. AUTHOR
  222.  
  223.       Doug Harrison
  224.  
  225.       Electronic mail:
  226.  
  227.          GEnie: D.S.HARRISON
  228.          Bix: dharrison
  229.          Compuserve: 72277,2315
  230.  
  231.       U.S. Mail:
  232.  
  233.          Doug Harrison
  234.          P.O. Box 66236
  235.          Baton Rouge, LA 70806-6236
  236.  
  237.       Please send any comments and criticisms to any of the above
  238.       addresses.  Shareware donations cheerfully accepted! (see the
  239.       accompanying README.TXT file for details on this and distribution
  240.       instructions)
  241.